<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Put index template API | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="indices.html" title="Index APIs">
<link rel="prev" href="indices-open-close.html" title="Open index API">
<link rel="next" href="indices-put-mapping.html" title="Put mapping API">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="indices.html">Index APIs</a></span>
»
<span class="breadcrumb-node">Put index template API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="indices-open-close.html">« Open index API</a>
</span>
<span class="next">
<a href="indices-put-mapping.html">Put mapping API »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="indices-templates"></a>Put index template API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h2>
</div></div></div>

<p>Creates or updates an index template.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT _template/template_1
{
  "index_patterns": ["te*", "bar*"],
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "_source": {
      "enabled": false
    },
    "properties": {
      "host_name": {
        "type": "keyword"
      },
      "created_at": {
        "type": "date",
        "format": "EEE MMM dd HH:mm:ss Z yyyy"
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1687.console"></div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-index-template-api-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">PUT /_template/&lt;index-template&gt;</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-index-template-api-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Use the PUT index template API
to create or update an index template.</p>
<p>Index templates define <a class="xref" href="index-modules.html#index-modules-settings" title="Index Settings">settings</a> and <a class="xref" href="mapping.html" title="Mapping">mappings</a>
that you can automatically apply when creating new indices.
Elasticsearch applies templates to new indices
based on an index pattern that matches the index name.</p>
<p>Index templates are only applied during index creation.
Changes to index templates do not affect existing indices.
Settings and mappings specified in <a class="xref" href="indices-create-index.html" title="Create index API">create index</a> API requests
override any settings or mappings specified in an index template.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_comments_in_index_templates"></a>Comments in index templates<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h4>
</div></div></div>
<p>You can use C-style /* */ block comments in index templates.
You can include comments anywhere in the request body,
except before the opening curly bracket.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="getting"></a>Getting templates<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h4>
</div></div></div>
<p>See <a class="xref" href="indices-get-template.html" title="Get index template API">Get index template</a>.</p>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-index-template-api-path-params"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;index-template&gt;</code>
</span>
</dt>
<dd>
(Required, string)
Name of the index template to create.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-index-template-api-query-params"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">create</code>
</span>
</dt>
<dd>
(Optional, boolean)
If <code class="literal">true</code>, this request cannot replace or update existing index templates.
Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">order</code>
</span>
</dt>
<dd>
<p>
(Optional,integer)
Order in which Elasticsearch applies this template
if index matches multiple templates.
</p>
<p>Templates with lower <code class="literal">order</code> values are merged first.
Templates with higher <code class="literal">order</code> values are merged later,
overriding templates with lower values.</p>
</dd>
<dt>
<span class="term">
<code class="literal">master_timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a connection to the master node. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-index-template-api-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">index_patterns</code>
</span>
</dt>
<dd>
(Required, array of strings)
Array of wildcard expressions
used to match the names of indices during creation.
</dd>
<dt>
<span class="term">
<code class="literal">aliases</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="indices-aliases.html" title="Update index alias API">alias object</a>) Index aliases which include the
index. See <a class="xref" href="indices-aliases.html" title="Update index alias API">Update index alias</a>.
</dd>
<dt>
<span class="term">
<code class="literal">mappings</code>
</span>
</dt>
<dd>
<p>(Optional, <a class="xref" href="mapping.html" title="Mapping">mapping object</a>) Mapping for fields in the index. If
specified, this mapping can include:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Field names
</li>
<li class="listitem">
<a class="xref" href="mapping-types.html" title="Field datatypes">Field datatypes</a>
</li>
<li class="listitem">
<a class="xref" href="mapping-params.html" title="Mapping parameters">Mapping parameters</a>
</li>
</ul>
</div>
<p>See <a class="xref" href="mapping.html" title="Mapping">Mapping</a>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">settings</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="index-modules.html#index-modules-settings" title="Index Settings">index setting object</a>) Configuration
options for the index. See <a class="xref" href="index-modules.html#index-modules-settings" title="Index Settings">Index Settings</a>.
</dd>
<dt>
<span class="term">
<code class="literal">version</code>
</span>
</dt>
<dd>
(Optional, integer)
Version number used to manage index templates externally.
This number is not automatically generated by Elasticsearch.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-index-template-api-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_index_template_with_index_aliases"></a>Index template with index aliases<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h4>
</div></div></div>
<p>You can include <a class="xref" href="indices-aliases.html" title="Update index alias API">index aliases</a> in an index template.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT _template/template_1
{
    "index_patterns" : ["te*"],
    "settings" : {
        "number_of_shards" : 1
    },
    "aliases" : {
        "alias1" : {},
        "alias2" : {
            "filter" : {
                "term" : {"user" : "kimchy" }
            },
            "routing" : "kimchy"
        },
        "{index}-alias" : {} <a id="CO570-1"></a><i class="conum" data-value="1"></i>
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1688.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO570-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>the <code class="literal">{index}</code> placeholder in the alias name will be replaced with the
actual index name that the template gets applied to, during index creation.</p>
</td>
</tr>
</table>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="multiple-templates"></a>Indices matching multiple templates<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Multiple index templates can potentially match an index, in this case,
both the settings and mappings are merged into the final configuration
of the index. The order of the merging can be controlled using the
<code class="literal">order</code> parameter, with lower order being applied first, and higher
orders overriding them. For example:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_template/template_1
{
    "index_patterns" : ["*"],
    "order" : 0,
    "settings" : {
        "number_of_shards" : 1
    },
    "mappings" : {
        "_source" : { "enabled" : false }
    }
}

PUT /_template/template_2
{
    "index_patterns" : ["te*"],
    "order" : 1,
    "settings" : {
        "number_of_shards" : 1
    },
    "mappings" : {
        "_source" : { "enabled" : true }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1689.console"></div>
<p>The above will disable storing the <code class="literal">_source</code>, but
for indices that start with <code class="literal">te*</code>, <code class="literal">_source</code> will still be enabled.
Note, for mappings, the merging is "deep", meaning that specific
object/property based mappings can easily be added/overridden on higher
order templates, with lower order templates providing the basis.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Multiple matching templates with the same order value will
result in a non-deterministic merging order.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="versioning-templates"></a>Template versioning<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/templates.asciidoc">edit</a>
</h4>
</div></div></div>
<p>You can use the <code class="literal">version</code> parameter
to add an optional version number to an index template.
External systems can use these version numbers
to simplify template management.</p>
<p>The <code class="literal">version</code>	parameter is completely optional
and not automatically generated by Elasticsearch.</p>
<p>To unset a <code class="literal">version</code>,
replace the template without specifying	one.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_template/template_1
{
    "index_patterns" : ["*"],
    "order" : 0,
    "settings" : {
        "number_of_shards" : 1
    },
    "version": 123
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1690.console"></div>
<p>To check the <code class="literal">version</code>,
you can	use the <a class="xref" href="indices-get-template.html" title="Get index template API">get index template</a> API
with the <a class="xref" href="common-options.html#common-options-response-filtering" title="Response Filtering"><code class="literal">filter_path</code></a> query parameter
to return only the version number:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_template/template_1?filter_path=*.version</pre>
</div>
<div class="console_widget" data-snippet="snippets/1691.console"></div>
<p>The API returns the following response:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "template_1" : {
    "version" : 123
  }
}</pre>
</div>
</div>

</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="indices-open-close.html">« Open index API</a>
</span>
<span class="next">
<a href="indices-put-mapping.html">Put mapping API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
